home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / basic / pbasmlib.zip / SCREEN.DOC < prev    next >
Text File  |  1994-02-12  |  17KB  |  485 lines
  1. PBASMLIB Assembly Language Routines for PB3C
  2. Version 1.0
  3. Text Screen/Memory Routines (SCREEN.ASM)
  4. (C) Copyright 1994 by Tim Gerchmez
  5. All Rights Reserved.
  6.  
  7. This module includes routines that let you manipulate text screens
  8. and memory directly (read FAST!).  It is included in the PBASMLIB.PBL
  9. library, and the routines contained herein will be immediately accessible
  10. to your programs by using the statements $INCLUDE "PBASMLIB.INC" and
  11. $LINK "PBASMLIB.PBL" at the top of your programs.
  12.  
  13. Note: For fastest speed possible, these routines do not
  14.       do "snow checking" on CGA monitors.  If this feature
  15.       is requested in a future version, it may be added.
  16.  
  17. All routines that directly manipulate the text screen work
  18. with the currently visible page, unless otherwise noted.
  19. All routines support 80x25 color text mode.  Some routines
  20. will support other modes (40x25, 80x43, etc).  When in doubt
  21. try the mode you want with a particular routine - it won't do
  22. any damage.
  23.  
  24. ================================================================================
  25. sub blankin  <MCGA, VGA ONLY>
  26.  
  27. Makes the contents of the screen reappear instantly after using FADEOUT
  28. or BLANKOUT.  FADEIN does the same thing, but slowly.  Note that you
  29. cannot use blankin while the screen is visible - it must have been blanked
  30. with BLANKOUT or faded with FADEOUT first.
  31.  
  32. Example: blankout  'Hide the screen
  33.          color 15,1:cls
  34.          print "This is a test"
  35.          blankin   'Make the screen visible
  36.  
  37. ================================================================================
  38. sub blankout   <MCGA, VGA ONLY>
  39.  
  40. Blanks the contents of the screen out instantly.  You can then
  41. change the screen contents "behind the scenes," and use FADEIN to
  42. fade the new screen contents into view, or BLANKIN to instantly reshow
  43. the screen.  Note that you cannot use blankout after using fadeout - the
  44. screen contents must be currently faded in (visible) for this routine to work.
  45.  
  46. Example:  CLS  'clears the screen first
  47.           call blankout  'Blanks screen, preparing for fadein
  48.           locate 10,10:print "THIS IS A TEST"  'This won't show up right away
  49.           fadein 20         'Fade the screen in slowly now
  50.  
  51. ================================================================================
  52. SUB blockfill (seg??,ofs??,nbytes??,byte%)
  53.  
  54. Fills an area of memory with a byte value.
  55.  
  56. seg??: Set to start segment of memory area to fill
  57. ofs??: Set to start offset of memory area to fill
  58. nbytes??: Set to number of bytes to fill (1-65535)
  59. byte%: Set to byte value to fill memory with
  60.  
  61. Example: blockfill &hb800,0,4000,32  'Clear Screen
  62.  
  63. ================================================================================
  64. SUB Blockmove(sseg??,sofs??,dseg??,dofs??,nbytes??)
  65.  
  66. Moves a block of memory from one place to another
  67. (actually makes a copy, doesn't change original).
  68.  
  69. sseg??: Set to source segment to move
  70. sofs??: Set to source offset to move
  71. dseg??: Set to destination segment to move
  72. dofs??: Set to destination offset to move
  73. nbytes??: Set to number of bytes to move (1-65535)
  74.  
  75. Example: blockmove &hb800,0,&hb800,&h1000,4000 'Copy text page 0 to page 1
  76.  
  77. ================================================================================
  78. FUNCTION calcaddr(y%,x%)
  79.  
  80. Calculates an absolute screen offset address,
  81. given Y and X positions.
  82.  
  83. y%: Set to Y location (row) (1-25) on screen
  84. x%: Set to X location (column) (1-80) on screen
  85. calcaddr: Returns absolute text screen offset address
  86. (80x25 screen) - 0-4000.
  87.  
  88. Example: print calcaddr(15,5)
  89.  
  90. ================================================================================
  91. FUNCTION calcattr(fgd%,bckg%)
  92.  
  93. Returns an attribute byte value, given a foreground
  94. and background color.  Opposite of calcucolors.
  95.  
  96. fgd%: Set to foreground character color
  97. bckg%: Set to background character color
  98. calcattr: Returns attribute byte value (FN)
  99.  
  100. Example: a%=calcattr(10,1)
  101.  
  102. ================================================================================
  103. SUB calcucolors(attr%, foregd%, bckg%)
  104.  
  105. Given a screen attribute value, returns foreground
  106. and background colors to be used with the COLOR statement.
  107. Opposite of CALCATTR.
  108.  
  109. attr%: Set to attribute value (0-255)
  110. foregd%: Returns foreground character color value
  111. bckg%: Returns background character color value
  112.  
  113. Example: calcucolors 31,f%,b%
  114.  
  115. ================================================================================
  116. SUB calcyx(offset%,y%,x%)
  117.  
  118. Given an absolute text screen offset address,
  119. calculates the Y (row) and X (column) locations
  120. on the screen (80x25 screen).  Opposite of CALCADDR.
  121.  
  122. offset%: Set to absolute text screen offset value
  123. y%: Returns Y position (1-25) in y%
  124. x%: Returns X position (1-80) in x%
  125.  
  126. Example: calcyx 320,y%,x%
  127.  
  128. ================================================================================
  129. SUB caveincls(delay%)
  130.  
  131. Clears the screen by "caving it in" on itself.
  132. Uses the current color values set by COLOR.
  133.  
  134. d%: Set to delay value (15-20 is about right)
  135.  
  136. Example: caveincls 15
  137.  
  138. ================================================================================
  139. SUB caveoutcls(delay%)
  140.  
  141. Clears the screen by "caving it outward."
  142. Uses the current color values set by COLOR.
  143.  
  144. d%: Set to delay value (15-20 is about right)
  145.  
  146. Example: caveoutcls 15
  147.  
  148. ================================================================================
  149. SUB clearline(ln%)
  150.  
  151. Clears the text screen line specified.
  152.  
  153. ln%: Set to screen line to clear (normally 1-25)
  154.  
  155. Example: clearline 25  'clear bottom screen line
  156.  
  157. ================================================================================
  158. SUB clsto(fgd%,bkg%)
  159.  
  160. Similar to CLS, but works only in text modes, and lets
  161. you "clear to" any color you want without changing the
  162. COLOR attributes or the cursor location.  Essentially a
  163. way of changing screen background colors, but clears the
  164. screen at the same time.
  165.  
  166. fgd%: Set to foreground color of new, cleared screen
  167. bkg%: Set to background color of new, cleared screen
  168.  
  169. Example: clsto 31  'Blue screen, bright white "spaces"
  170.  
  171. ================================================================================
  172. SUB dscroll (uly%,ulx%,lry%,lrx%,atr%)
  173.  
  174. Scrolls a portion of the screen down by one row.
  175.  
  176. uly%: Set to upper left Y position (1-25)
  177. ulx%: Set to upper left X position (1-80)
  178. lry%: Set to lower right Y position (1-25)
  179. lrx%: Set to lower right X position (1-80)
  180. atr%: Set to attribute to scroll into blanked area
  181.  
  182. Example: dscroll 1,1,25,80,1
  183.  
  184. ================================================================================
  185. sub fadein(dly%)      <MCGA, VGA ONLY>
  186.  
  187. Fades the screen in after fading it out with FADEOUT or blanking with
  188. BLANKOUT.  You can change the contents of the screen while it's faded out,
  189. then call fadein to fade the new screen in.  See FADEOUT and BLANKOUT for
  190. more information.  The delay value you provide lengthens the time it takes
  191. to fade in as the value increases.  Fadein works with most screen modes,
  192. graphics and text included.
  193.  
  194. dly%: Set to delay value (0-32767)
  195.  
  196. Example: fadein 20  'Fade the screen in with a delay value of 20
  197.  
  198. ================================================================================
  199. sub fadeout(dly%)   <MCGA, VGA ONLY>
  200.  
  201. Allows you to slowly fade the contents of the screen out in any
  202. screen mode, graphics or text.  You can then change the contents of
  203. the screen if desired, and fade it back in using FADEIN, or make it
  204. reappear instantly using BLANKIN.  The delay value you provide to
  205. FADEOUT will lengthen the time it takes to fade out as the value gets
  206. higher.
  207.  
  208. dly%: Set to delay value (0-32767)
  209.  
  210. Example: fadeout 20   'Fade the screen out
  211.          sleep        'Wait for a keypress
  212.          fadein 20    'Fade the screen back in
  213.  
  214. ================================================================================
  215. sub faderestore  <MCGA, VGA  with PC/AT or PS/2 ONLY>
  216.  
  217. Restores the normal screen if CTRL-BREAK was pressed during a FADEIN
  218. or FADEOUT.  This will leave the screen in a partially faded state, and
  219. FADERESTORE will change the screen back to its default values.  If this
  220. routine is used on a PC/XT, the screen will be cleared and screen contents
  221. lost, or the result may be unpredictable.
  222.  
  223. Example: call faderestore
  224.  
  225. ================================================================================
  226. SUB fastprint(s$,attrib%,y%,x%)
  227.  
  228. Prints very quickly to the screen, using direct
  229. video buffer access.  Prints to currently visible
  230. page.
  231.  
  232. s$: Set to string to print.  Cursor is not updated
  233.     and no CRLF is performed afterward.
  234. attrib%: Set to attribute to print string in
  235. y%: Set to Y position (normally 1-25) on screen to print at
  236. x%: Set to X position (normally 1-80) on screen to print at
  237.  
  238. Example: fastprint "Testing",7,1,1
  239.  
  240. ================================================================================
  241. SUB fillattr(x%)
  242.  
  243. Fills the text screen with the attribute specified.
  244. CALL fillattr(x%), where x%=0-255.
  245. Uses current visual screen page (normally 0).
  246.  
  247. Example: fillattr 31  'Set screen to white-on-blue
  248.  
  249. ================================================================================
  250. SUB fillchar(x%)
  251.  
  252. Fills the text screen with the ASCII character specified.
  253. Syntax: CALL fillchar(x%), where x%=0 to 255
  254. Uses PowerBASIC's "active" screen page (normally 0).
  255.  
  256. Example: fillchar 65  'Fill screen with "A"
  257.  
  258. ================================================================================
  259. SUB lscroll(uly%,ulx%,lry%,lrx%,atr%)
  260.  
  261. Scrolls a portion of the screen left by one column.
  262.  
  263. uly%: Set to upper left Y position (1-25)
  264. ulx%: Set to upper left X position (1-80)
  265. lry%: Set to lower right Y position (1-25)
  266. lrx%: Set to lower right X position (1-80)
  267. atr%: Set to attribute to scroll into blanked area
  268.  
  269. Example: call lscroll(uly%,ulx%,lry%,lrx%,atr%)
  270.  
  271. ================================================================================
  272. SUB pgcopy(source%,dest%)
  273.  
  274. Allows copying of one text-screen page to another,
  275. mimicking QuickBASIC's PCOPY command in text mode.
  276. This will not work with a monochrome card, since
  277. only one screen page is available.
  278. No check is done for illegal values, so be careful.
  279.  
  280.  
  281. source%: Set to source page (0-3 CGA, 0-7 EGA/VGA) to copy
  282. dest%: Set to destination page (0-3 CGA, 0-7 EGA/VGA) to copy
  283.  
  284. Example: pgcopy 0,1
  285.  
  286. ================================================================================
  287. SUB pglayer(source%,dest%)
  288.  
  289. Similar to PGCOPY, but only stores the source to the
  290. destination if the destination is blank at the stored
  291. spots.  This has the effect of "layering" the source
  292. screen onto the destination screen.  Will not work with
  293. monochrome card, since only one page is available.  No
  294. check is done for illegal values, so be careful.
  295.  
  296. source%: Set to source page (0-3 CGA, 0-7 EGA/VGA)
  297. dest%: Set to destination page (0-3 CGA, 0-7 EGA/VGA)
  298.  
  299. Example: pglayer 1,0
  300.  
  301. ================================================================================
  302. SUB pgswap(page1%,page2%)
  303.  
  304. Allows you to swap the contents of two text-screen pages,
  305. replacing one with the other.  Won't work with a monochrome
  306. card, as only one screen page is available.  No check is done
  307. for illegal values, so be careful.
  308.  
  309. page1%:Set to first page (0-3 CGA, 0-7 EGA/VGA)
  310. page2%: Set to second page (0-3 CGA, 0-7 EGA/VGA)
  311.  
  312. Example: pgswap 0,1  'Swaps the contents of page 0 and page 1
  313.  
  314. ================================================================================
  315. SUB readchar(y%,x%,ch%,atr%)
  316.  
  317. Reads a character from the visible text screen page
  318. (80x25 only), and returns character/attribute values.
  319. MUCH faster than using the SCREEN function.
  320.  
  321. y%: Set to text screen Y offset (1-25) to read
  322. x%: Set to text screen X offset (1-80) to read
  323. ch%: Returns character value at y%,x%
  324. atr%: Returns attribute value at y%,x%
  325.  
  326. Example: readchar 1,1,ch%,atr%
  327.  
  328. ================================================================================
  329. SUB reattr(oldattr%,newattr%)
  330.  
  331. Changes all specified attributes on the text screen
  332. (visible page) to a new attribute.  This allows you to
  333. recolor only specific portions of the screen.
  334.  
  335. oldattr%: Set to old attribute to change
  336. newattr%: Replaces all old attributes found with new attributes
  337.  
  338. Example: reattr 7,31
  339.  
  340. ================================================================================
  341. SUB rechar(oldchar%,newchar%)
  342.  
  343. Changes all specified characters on the text screen
  344. (visible page) to a new character.
  345.  
  346. oldchar%: Set to old character to change
  347. newchar%: Replaces all old characters found with new character
  348.  
  349. Example: rechar 32,asc(".")  'Changes all spaces on screen to dots
  350.  
  351. ================================================================================
  352. SUB restorearea(uly%,ulx%,s$)
  353.  
  354. Allows you to restore an area of the screen
  355. previously saved with SAVEAREA$.
  356.  
  357. uly%: Set to upper-left Y position to restore area to
  358. ulx%: Set to upper-left X position to restore area to
  359. s$: Set to string previously retrieved with SAVEAREA$
  360.  
  361. Example: restorearea 1,1,s$
  362.  
  363. ================================================================================
  364. SUB restoretextarea(uly%,ulx%,s$)
  365.  
  366. Restores an area of the screen (text portion only)
  367. previously saved with SAVETEXTAREA.
  368.  
  369. uly%: Set to upper-left Y position to restore area to
  370. ulx%: Set to upper-left X position to restore area to
  371. s$: Set to string previously retrieved with SAVETEXTAREA$
  372.  
  373. Example: restoretextarea 1,1,s$
  374.  
  375. ================================================================================
  376. SUB rscroll(uly%,ulx%,lry%,lrx%,atr%)
  377.  
  378. Scrolls a portion of the screen right by one column.
  379.  
  380. uly%: Set to upper left Y position (1-25)
  381. ulx%: Set to upper left X position (1-80)
  382. lry%: Set to lower right Y position (1-25)
  383. lrx%: Set to lower right X position (1-80)
  384. atr%: Set to attribute to scroll into blanked area
  385.  
  386. Example: rscroll 1,1,25,80,7
  387.  
  388. ================================================================================
  389. function savearea$(uly%,ulx%,lry%,lrx%)
  390.  
  391. Saves an area of the text screen (visual page)
  392. and returns a string holding the saved area.
  393.  
  394. uly%: Set to upper left Y position
  395. ulx%: Set to upper left X position
  396. lry%: Set to lower right Y position
  397. lrx%: Set to lower right X position
  398. savearea$: Returns string (see RESTOREAREA)
  399.  
  400. Example: s$=savearea$(1,1,25,80) 'Returns 4004-byte string
  401.  
  402. ================================================================================
  403. function savetextarea$(uly%,ulx%,lry%,lrx%)
  404.  
  405. Saves only the text portion of an area of the screen,
  406. thus using only half the memory.  Use RESTORETEXTAREA
  407. with the string returned by this routine to restore the
  408. saved area.
  409.  
  410. uly%: Set to upper left Y position
  411. ulx%: Set to upper left X position
  412. lry%: Set to lower right Y position
  413. lrx%: Set to lower right X position
  414. savetextarea$: Returns string (see RESTORETEXTAREA)
  415.  
  416. Example: s$=savetextarea$(1,1,25,80) 'returns 2004-byte string
  417.  
  418. ================================================================================
  419. SUB stepfill(seg??,ofs??,nbytes??,stepval%,byte%)
  420.  
  421. Fills an area of memory with a byte value, using a
  422. given step value.  Similar to a FOR-NEXT loop using
  423. a step value and POKE.  The fill starts at the given
  424. offset, and skips stepval%-1 bytes between each store.
  425. Useful for filling different types of arrays, and the screen.
  426.  
  427. seg??: Set to start segment of memory area to fill
  428. ofs??: Set to start offset of memory area to fill
  429. nbytes??: Set to number of bytes to fill (1-65535)
  430. stepval%: Set to step value (for example, stepval of
  431.           2 will fill every other byte, starting with
  432.           the first byte indicated in ofs??).
  433. byte%: Set to byte value to fill memory with
  434.  
  435. Example: stepfill &hb800,0,2000,2,asc("A") 'Fill the screen with "A"
  436.         stepfill &hb800,1,2000,2,31 'Then fill attribute bytes
  437.  
  438. ================================================================================
  439. SUB tearcls(delay%)
  440.  
  441. Clears the screen so that it appears to "tear" apart.
  442.  
  443. delay%: Set to delay value (15-20 is about right).
  444.  
  445. Example: tearcls 15
  446.  
  447. ================================================================================
  448. SUB uscroll (uly%,ulx%,lry%,lrx%,atr%)
  449.  
  450. Scrolls a portion of the screen up by one row.
  451.  
  452. uly%: Set to upper left Y position (1-25)
  453. ulx%: Set to upper left X position (1-80)
  454. lry%: Set to lower right Y position (1-25)
  455. lrx%: Set to lower right X position (1-80)
  456. atr%: Set to attribute to scroll into blanked area
  457.  
  458. Example: uscroll 1,1,25,80,7
  459.  
  460. ================================================================================
  461. FUNCTION vidseg
  462.  
  463. Returns current text-screen segment -
  464. &hb000 for monochrome or &hb800 for color.
  465.  
  466. vidseg: Returns video segment (FN)
  467.  
  468. Example: print vidseg
  469.  
  470. ================================================================================
  471. SUB writechar(y%,x%,ch%,atr%)
  472.  
  473. Writes a character to the active text screen page
  474. (80x25 only) using specified attribute value.
  475. MUCH faster than locate/color/print combination, and
  476. doesn't disturb cursor or COLOR settings.
  477.  
  478. y%: Set to text screen Y offset (1-25)
  479. x%: Set to text screen X offset (1-80)
  480. ch%: Set to ASCII value of character to write (0-255)
  481. atr%: Set to attribute value to write
  482.  
  483. Example:  writechar 1,1,1,31
  484.  
  485.